home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 24 / AACD 24.iso / AACD / Information / WebSites / Eyetech / DOWNLOAD / IOBLI016.LHA / IOBlixDevKit / AutoDocs / ioblix.doc next >
Text File  |  1999-04-28  |  18KB  |  475 lines
  1.  
  2. TABLE OF CONTENTS
  3.  
  4. ioblix.resource/--background--
  5. ioblix.resource/AddIRQHook
  6. ioblix.resource/AllocChipList
  7. ioblix.resource/FindChip
  8. ioblix.resource/FreeChipList
  9. ioblix.resource/ObtainChip
  10. ioblix.resource/ObtainChipShared
  11. ioblix.resource/ReleaseChip
  12. ioblix.resource/ReleaseChipShared
  13. ioblix.resource/RemIRQHook
  14.  
  15. ioblix.resource/--background--                   ioblix.resource/--background--
  16.  
  17.    PURPOSE
  18.       The ioblix.resource is created by SetupIOBlix during startup and provides
  19.       several functions to gain exclusive as well as shared access to any chip
  20.       the IOBlix multi I/O boards provide. If you ever want to use one of the
  21.       IOBlix chips you should ALWAYS use either ObtainChip() or
  22.       ObtainChipShared() to prevent other ioblix.resource-conform programs from
  23.       interferring with your program. All device drivers being delivered with
  24.       your IOBlix board follow this rule. And hopefully all third-party drivers
  25.       will also do.
  26.       To access these functions just call OpenResource(IOBLIXRESNAME) and use
  27.       the returned pointer in the same manner as library bases are used.
  28.  
  29.  
  30. ioblix.resource/AddIRQHook                           ioblix.resource/AddIRQHook
  31.  
  32.    NAME
  33.       AddIRQHook  - add a private interrupt function to the IOBlix interrupt
  34.                     chain
  35.  
  36.    SYNOPSIS
  37.       void = AddIRQHook( node )
  38.                          A0
  39.  
  40.       void AddIRQHook( struct IRQHookNode * );
  41.  
  42.    FUNCTION
  43.       Adds the given node to the IOBlix interrupt chain. This is necessary
  44.       because normal interrupt handling by AmigaOS will loose some interrupts on
  45.       heavy system load.
  46.       Just imagine two applications using the IOBlix board (eg one serial and
  47.       one parallel port). When adding your own interrupt function with Exec's
  48.       AddIntServer() the system will just recognize the first of two
  49.       simultaneously happening interrupts, because the first function will return
  50.       a successfull interrupt handling and Exec will cease any further handling
  51.       within its chain. But at this time the second interrupt has still not been
  52.       processed. IOBlix' own interrupt chain avoids this problem by checking all
  53.       active chips before returning control to Exec.
  54.       The function given in ihn_HookFunc will be passed the data given in
  55.       ihn_HookUserData on the stack. Just as Exec's interrupt handling functions
  56.       a return value of 0 indicates that no interrupt has happened. Any other
  57.       return value indicates a successfull interrupt handling.
  58.  
  59.    INPUTS
  60.       node     -- a correctly initialized IRQHookNode
  61.  
  62.    EXAMPLE
  63.       /* add a private interrupt function */
  64.       ULONG __saveds myIRQFunc( APTR userData);
  65.       APTR myUserData;
  66.       struct IRQHookNode *node;
  67.  
  68.       if (IOBlixBase = OpenResource(IOBLIXRESNAME)) {
  69.         node->ihn_Node.ln_Name = "TestHook";
  70.         node->ihn_Node.ln_Pri = 5; /* priority within the chain */
  71.         node->ihn_HookFunc = myIRQFunc;
  72.         node->ihn_HookUserData = myUserData;
  73.         AddIRQHook(node);
  74.         /* do whatever you want */
  75.         RemIRQHook(node);
  76.       }
  77.  
  78.       ULONG myIRQFunc( APTR userData )
  79.       {
  80.         /* check wether an interrupt has happened or not                   */
  81.         /* if yes, then do all necessary things and return a value of != 0 */
  82.         /* else just return 0                                              */
  83.       }
  84.  
  85.    SEE ALSO
  86.       RemIRQHook
  87.  
  88. ioblix.resource/AllocChipList                     ioblix.resource/AllocChipList
  89.  
  90.    NAME
  91.       AllocChipList -- get a list of all available chips
  92.  
  93.    SYNOPSIS
  94.       list = AllocChipList( void )
  95.       D0
  96.  
  97.       struct List *AllocChipList( void );
  98.  
  99.    FUNCTION
  100.       This function returns a copy of the internal list of all available chips.
  101.       You are allowed to iterate through the list, but you must not change
  102.       anything. All nodes in the list are of type (struct IOBlixChipNode *). No
  103.       chip in the list is obtained in a ObtainChip()-like manner.
  104.  
  105.    RESULTS
  106.       chipNode -- a list of all available chips, or NULL if the call failed
  107.  
  108.    EXAMPLE
  109.       /* print information about all IOBlix chips in the system */
  110.       struct IOBlixResource *IOBlixBase;
  111.       struct List *list;
  112.       struct IOBlixChipNode *node;
  113.  
  114.       if (IOBlixBase = OpenResource(IOBLIXRESNAME)) {
  115.         if (list = AllocChipList()) {
  116.           node = (struct IOBlixChipNode *)chipList->lh_Head;
  117.           while (node->icn_Node.ln_Succ) {
  118.             switch (node->icn_Type) {
  119.               case ICT_Z2_SERIAL_CHIP:
  120.                 printf("IOBlix Z2 UART, %s, %ld bytes FIFO\n",
  121.                        node->icn_Description, node->icns_FIFOSize);
  122.                 break;
  123.               case ICT_Z2_PARALLEL_CHIP:
  124.                 printf("IOBlix Z2 parallel port, %s, %ld bytes FIFO\n",
  125.                        node->icn_Description, node->icnp_FIFOSize);
  126.                 break;
  127.               default:
  128.                 break;
  129.               printf("chip is in use by %s\n",
  130.                      (node->icn_Owner) ? node->icn_Owner : "nobody");
  131.             }
  132.             node = (struct IOBlixChipNode *)node->icn_Node.ln_Succ);
  133.           }
  134.           FreeChipList(list);
  135.         } else {
  136.           printf("failed to allocate chip list\n");
  137.         }
  138.       }
  139.  
  140.    SEE ALSO
  141.       FreeChipList
  142.  
  143. ioblix.resource/FindChip                               ioblix.resource/FindChip
  144.  
  145.    NAME
  146.       FindChip -- find a chip in the resource's database
  147.  
  148.    SYNOPSIS
  149.       chipNode = FindChip(chipType, chipNum)
  150.       D0                  D0        D1
  151.  
  152.       struct IOBlixChipNode *FindChip( ULONG, ULONG );
  153.  
  154.    FUNCTION
  155.       This function searches the internal list for the chip matching the given
  156.       values for chip type and number. If the search is successfull the chip's
  157.       information block is returned, but the chip is NOT obtained!
  158.       You may use this function just to check if a certian chip is available
  159.       and to get some information about it. All fields in IOBlixChipNode are
  160.       considered READ-ONLY, you must not change anything.
  161.  
  162.    INPUTS
  163.       chipType -- the type of chip you want to find
  164.       chipNum  -- internal number of the chip you want to find
  165.                   valid range is 0..IOBLIX_Z2_NUM_SERUNITS for UARTs
  166.                                  0..IOBLIX_Z2_NUM_PARUNITS for parallel ports
  167.                                  0..IOBLIX_Z2_NUM_FIFOUNITS for external FIFOs
  168.                   to obtain a chip on multiple IOBlix boards use
  169.                   boardNum*10+chipNum as value, ie 13 is the third UART on the
  170.                   second board
  171.  
  172.    RESULTS
  173.       chipNode -- a pointer to the chip's information block, or NULL if the
  174.                   chip is not available.
  175.  
  176.    EXAMPLE
  177.       /* try to find serial unit 0 on first IOBlix board */
  178.       struct IOBlixResource *IOBlixBase;
  179.       struct IOBlixChipNode *chipInfo;
  180.  
  181.       if (IOBlixBase = OpenResource(IOBLIXRESNAME)) {
  182.         if (chipInfo = FindChip(ICT_Z2_SERIAL_CHIP, 0)) {
  183.           /* chip is available, let's see what it is able to do */
  184.           printf("UART is a %s with %ld bytes FIFO"\n,
  185.                  chipInfo->icn_Description, chipInfo->icns_FIFOSize);
  186.           printf("UART is in use by %s\n",
  187.                  (chipInfo->icn_Owner) ? chipInfo->icn_Owner : "nobody");
  188.         } else {
  189.           printf("serial port #0 is not available\n");
  190.         }
  191.       }
  192.  
  193.    SEE ALSO
  194.       ReleaseChip, FindChip
  195.  
  196. ioblix.resource/FreeChipList                       ioblix.resource/FreeChipList
  197.  
  198.    NAME
  199.       FreeChipList -- free a previously allocated chip list
  200.  
  201.    SYNOPSIS
  202.       void = FreeChipList( list )
  203.                            A0
  204.  
  205.       void FreeChipList( struct List * );
  206.  
  207.    FUNCTION
  208.       This function frees the given list again.
  209.  
  210.    INPUTS
  211.       list     -- a list previously allocated by AllocChipList(). Passing NULL
  212.                   is a no-op.
  213.  
  214.    SEE ALSO
  215.       AllocChipList
  216.  
  217. ioblix.resource/ObtainChip                           ioblix.resource/ObtainChip
  218.  
  219.    NAME
  220.       ObtainChip -- obtain a chip for exclusive use
  221.  
  222.    SYNOPSIS
  223.       chipNode = ObtainChip(chipType, chipNum, newOwner, oldOwner)
  224.       D0                    D0        D1          A0        A1
  225.  
  226.       struct IOBlixChipNode *ObtainChip( ULONG, ULONG, UBYTE *, UBYTE ** );
  227.  
  228.    FUNCTION
  229.       This function attempts to obtain the specified chip for exclusive use.
  230.       The name newOwner is used as an identifier to tell other programs who
  231.       currently has obtained the chip.
  232.       If the chip is not in use by anybody then the IOBlixChipNode of this chip
  233.       is returned to show a successfull allocation. If the chip is already in
  234.       use then the return value will be NULL, and the identifier of the using
  235.       program is retured in oldOwner, if a valid pointer is given. If also
  236.       oldOwner is still NULL then the chip is not available.
  237.  
  238.    INPUTS
  239.       chipType -- the type of chip you want to obtain
  240.       chipNum  -- internal number of the chip you want to obtain
  241.                   valid range is 0..IOBLIX_Z2_NUM_SERUNITS for UARTs
  242.                                  0..IOBLIX_Z2_NUM_PARUNITS for parallel ports
  243.                                  0..IOBLIX_Z2_NUM_FIFOUNITS for external FIFOs
  244.                   to obtain a chip on multiple IOBlix boards use
  245.                   boardNum*10+chipNum as value, ie 13 is the third UART on the
  246.                   second board
  247.       newOwner -- a string to identify you as the current owner of the chip
  248.       oldOwner -- pointer to a string where the identfier of a previous owner
  249.                   will be placed. If NULL then it will not be used.
  250.  
  251.    RESULTS
  252.       chipNode -- If the chip is available and not in use then chipNode will be
  253.                   a pointer to IOBlixChipNode, which contains various
  254.                   information about the chip. If the chip is either not
  255.                   available or already obtained by someone else, this function
  256.                   will return NULL. Use oldOwner to check if the chip is
  257.                   already in use.
  258.       oldOwner -- If given a valid pointer and the chip is obtained by someone
  259.                   else, the previous allocators identifier will be placed here.
  260.  
  261.    EXAMPLE
  262.       /* try to obtain serial unit 0 on first IOBlix board */
  263.       struct IOBlixResource *IOBlixBase;
  264.       struct IOBlixChipNode *chipInfo;
  265.       UBYTE *oldOwner = NULL;
  266.  
  267.       if (IOBlixBase = OpenResource(IOBLIXRESNAME)) {
  268.         if (chipInfo = ObtainChip(ICT_Z2_SERIAL_CHIP, 0, "Test", &oldOwner)) {
  269.           /* chip is obtained now, do whatever you want */
  270.           ReleaseChip(chipInfo);
  271.         } else {
  272.           if (oldOwner) {
  273.             printf("serial port #0 is in use by %s\n", oldOwner);
  274.           } else {
  275.             printf("serial port #0 is not available\n");
  276.           }
  277.         }
  278.       }
  279.  
  280.    SEE ALSO
  281.       ObtainChipShared, ReleaseChip, ReleaseChipShared, FindChip
  282.  
  283. ioblix.resource/ObtainChipShared               ioblix.resource/ObtainChipShared
  284.  
  285.    NAME
  286.       ObtainChipShared -- obtain a chip for shared use
  287.  
  288.    SYNOPSIS
  289.       chipNode = ObtainChipShared(chipType, chipNum, newOwner, oldOwner)
  290.             D0                    D0        D1          A0        A1
  291.  
  292.       struct IOBlixChipNode *ObtainChipShared( ULONG, ULONG,
  293.                                                UBYTE *, UBYTE ** );
  294.  
  295.    FUNCTION
  296.       This function attempts to obtain the specified chip for shared use.
  297.       The name newOwner is used as an identifier to tell other programs who
  298.       currently has obtained the chip.
  299.       If the chip is not in use by anybody or already obtained in shared mode
  300.       then the IOBlixChipNode of this chip is returned to show a successfull
  301.       allocation. If the chip is already obtained in exclusive mode the return
  302.       value will be NULL, and the identifier of the using program is retured in
  303.       oldOwner, if a valid pointer is given. If also oldOwner is still NULL then
  304.       the chip is not available.
  305.  
  306.       When using a chip in shared mode you MUST use the semaphore contained in
  307.       the returned IOBlixChipNode while accessing the chip with Exec's semaphore
  308.       functions to gain exclusive access for a short time. After that you MUST
  309.       give access back to the system again with exec.library/ReleaseSemaphore.
  310.       When you got access to the chip you should save the important registers of
  311.       the chip (ie the control register of a parallel port), then put the values
  312.       you need there. Before calling ReleaseSemaphore() on the IOBlixChipNode's
  313.       semaphore you should put the previously saved values back to the important
  314.       registers to leave the chip in a specified state.
  315.  
  316.       When this call succeeds the ICFF_SHARED flag will be set in the chip
  317.       node's icn_Flags field. It will remain set unless the last user has
  318.       released the chip with ReleaseChipShared(). The list
  319.       icn_SharedAccessorList contains all users, while icn_Owner just contains
  320.       the string "shared use".
  321.  
  322.    INPUTS
  323.       chipType -- the type of chip you want to obtain
  324.       chipNum  -- internal number of the chip you want to obtain
  325.                   valid range is 0..IOBLIX_Z2_NUM_SERUNITS for UARTs
  326.                                  0..IOBLIX_Z2_NUM_PARUNITS for parallel ports
  327.                                  0..IOBLIX_Z2_NUM_FIFOUNITS for external FIFOs
  328.                   to obtain a chip on multiple IOBlix boards use
  329.                   boardNum*10+chipNum as value, ie 13 is the third UART on the
  330.                   second board
  331.       newOwner -- a string to identify you as the current owner of the chip
  332.       oldOwner -- pointer to a string where the identfier of a previous owner
  333.                   will be placed. If NULL then it will not be used.
  334.  
  335.    RESULTS
  336.       chipNode -- If the chip is available and not in use then chipNode will be
  337.                   a pointer to IOBlixChipNode, which contains various
  338.                   information about the chip. If the chip is either not
  339.                   available or already obtained by someone else, this function
  340.                   will return NULL. Use oldOwner to check if the chip is
  341.                   already in use.
  342.       oldOwner -- If given a valid pointer and the chip is obtained by someone
  343.                   else, the previous allocators identifier will be placed here.
  344.  
  345.    EXAMPLE
  346.       /* try to obtain serial unit 0 on first IOBlix board */
  347.       struct IOBlixResource *IOBlixBase;
  348.       struct IOBlixChipNode *chipInfo;
  349.       struct UARTRegisters *uart;
  350.       UBYTE *oldOwner = NULL;
  351.       UBYTE scratch
  352.  
  353.       if (IOBlixBase = OpenResource(IOBLIXRESNAME)) {
  354.         if (chipInfo = ObtainChipShared(ICT_Z2_SERIAL_CHIP, 0,
  355.                                         "Test", &oldOwner)) {
  356.           /* chip is obtained in shared mode now */
  357.           uart = (struct UARTRegisters *)chipInfo->icn_ChipRegisters;
  358.  
  359.           /* now access the chip exclusively for a short time */
  360.           ObtainSemaphore(&chipInfo->icn_SharedAccessSema);
  361.  
  362.           /* first save some importan registers */
  363.           scratch = *uart->ur_scr;
  364.  
  365.           /* now do whatever you want */
  366.           *uart->ur_scr = 0x42;
  367.  
  368.           /* put back the saved registers */
  369.           *uart->ur_scr = scratch;
  370.  
  371.           /* release the chip from exclusive access */
  372.           ReleaseSemaphore(&chipInfo->icn_SharedAccessSema);
  373.  
  374.           /* completely release the chip */
  375.           ReleaseChipShared(chipInfo, "Test");
  376.         } else {
  377.           if (oldOwner) {
  378.             printf("serial port #0 is in use by %s\n", oldOwner);
  379.           } else {
  380.             printf("serial port #0 is not available\n");
  381.           }
  382.         }
  383.       }
  384.  
  385.    SEE ALSO
  386.       ObtainChip, ReleaseChip, ReleaseChipShared, FindChip
  387.  
  388. ioblix.resource/ReleaseChip                         ioblix.resource/ReleaseChip
  389.  
  390.    NAME
  391.       ReleaseChip -- release a previously obtained chip from exclusive use
  392.  
  393.    SYNOPSIS
  394.       ReleaseChip(chipNode)
  395.                   A0
  396.  
  397.       void ReleaseChip( struct IOBlixChipNode * );
  398.  
  399.    FUNCTION
  400.       ReleaseChip() is the inverse of ObtainChip(). After calling ReleaseChip()
  401.       the given chip is available again for others.
  402.  
  403.       Each ObtainChip() call must be balanced by exactly one ReleaseChip() call.
  404.       Needless to say, havoc breaks out if the task releases a chip more times
  405.       than it has obtained it.
  406.  
  407.    INPUTS
  408.       chipNode -- the node previously returned by ObtainChip(). Passing NULL is
  409.                   a no-op.
  410.  
  411.    NOTES
  412.       Never release a shared obtained chip with ReleaseChip()!
  413.  
  414.    SEE ALSO
  415.       ObtainChip, ObtainChipShared, ReleaseChipShared
  416.  
  417. ioblix.resource/ReleaseChipShared             ioblix.resource/ReleaseChipShared
  418.  
  419.    NAME
  420.       ReleaseChipShared -- release a previously obtained chip from shared use
  421.  
  422.    SYNOPSIS
  423.       ReleaseChipShared(chipNode, owner)
  424.                         A0        A1
  425.  
  426.       void ReleaseChipShared( struct IOBlixChipNode *, UBYTE * );
  427.  
  428.    FUNCTION
  429.       ReleaseChipShared () is the inverse of ObtainChipShared().
  430.  
  431.       Each ObtainChipShared() call must be balanced by exactly one
  432.       ReleaseChipShared() call. Needless to say, havoc breaks out if the task
  433.       releases a chip more times than it has obtained it. The chip remains in
  434.       shared mode unless all obtainers have released it.
  435.  
  436.       You should call ReleaseChipShared() with the same owner name as
  437.       ObtainChipShared(), else the chip will remain obtained.
  438.  
  439.       When the last obtainer calls ReleaseChipShared() the ICFF_SHARED flag will
  440.       be reset.
  441.  
  442.    INPUTS
  443.       chipNode -- the node previously returned by ObtainChipShared(). Passing
  444.                   NULL is a no-op.
  445.       owner    -- the same owner as used for ObtainChipShared()
  446.  
  447.  
  448.    NOTES
  449.       Never release an exclusively obtained chip with ReleaseChipShared()!
  450.  
  451.    SEE ALSO
  452.       ObtainChip, ObtainChipShared, ReleaseChip
  453.  
  454. ioblix.resource/RemIRQHook                           ioblix.resource/RemIRQHook
  455.  
  456.    NAME
  457.       RemIRQHook  - remove a previously installed interrupt function
  458.  
  459.    SYNOPSIS
  460.       void = RemIRQHook( node )
  461.                          A0
  462.  
  463.       void RemIRQHook( struct IRQHookNode * );
  464.  
  465.    FUNCTION
  466.       Removes the given node from IOBlix' own interrupt chain.
  467.  
  468.    INPUTS
  469.       node     -- a correctly initialized IRQHookNode
  470.  
  471.    SEE ALSO
  472.       AddIRQHook
  473.  
  474.  
  475.